…plicate shell checker (#4)

## Summary

The bundle stops reimplementing what `anc` already does and pivots to a
guide that teaches agents how to use `anc`,
navigate the spec, and apply remediation patterns. Three architectural
changes in one commit because they only make
sense together:

1. **Vendor `agentnative-spec` as the canonical principle source.**
`scripts/sync-spec.sh` mirrors agentnative-cli's
vendoring script, retargeted to `bundle/spec/`. Pinned at `v0.2.0`
(matches the agentnative-cli pin). The vendored
tree carries machine-readable `requirements[]` frontmatter — the
contract `anc` reads.
2. **Delete content that duplicates anc.**
`bundle/scripts/check-compliance.sh` + 24 `check-*.sh` files were a
hand-rolled shell-script reimplementation of a Rust-source-only subset
of `anc`'s check matrix. `anc` supersedes
them (behavioral + project + source layers, JSON scorecard,
`requirement_id` citations, audit profiles).
`bundle/references/principles-deep-dive.md` was a 419-line hand-typed
paraphrase of the spec — replaced by the
vendored `bundle/spec/principles/`. `bundle/checklists/new-tool.md` was
a pre-anc 4-phase manual checklist whose
Phase 4 invoked the now-deleted shell scripts — replaced by
`bundle/getting-started.md`.
3. **Pivot SKILL.md and add getting-started.md.** SKILL.md drops inline
principle prose, points at
`bundle/spec/principles/` for canonical text, links `getting-started.md`
for progressive disclosure, frames the
three ecosystem artifacts (spec / `anc` / this skill).
`getting-started.md` covers the agent's three loops
(existing CLI / new Rust / other language), canonical `anc` invocations,
and a "where things live" map.

## Changelog

### Changed

- **Breaking (install layout):** Skill bundle stops shipping
`bundle/scripts/` and `bundle/checklists/`. Installers
and consumers should fetch only the surviving directories: `SKILL.md`,
`getting-started.md`, `spec/`, `references/`,
`templates/`. The consumer's installed skill-directory shape (`SKILL.md`
at the root) is unchanged.
- `bundle/SKILL.md` rewritten: drops inline principle prose, links
`bundle/getting-started.md` and
`bundle/spec/principles/` for progressive disclosure, frames the spec /
`anc` / skill three-artifact ecosystem.
- `RELEASES.md` SemVer guidance reframed around the bundle's actual
surface (markdown + templates + vendored spec)
rather than deleted shell-script exit codes; spec-bump-vs-skill-version
distinction documented.
- `.github/CODEOWNERS` no longer gates `bundle/scripts/**` (path
deleted); only producer-ops paths require review.
- `.github/workflows/ci.yml` shellcheck job now scans only `./scripts/`
(the bundle has no shell scripts to lint).
- `.github/ISSUE_TEMPLATE/bug_report.md` rewritten with a routing
prelude that sends `anc` bugs to agentnative-cli
  and spec-change requests to agentnative.

### Added

- `scripts/sync-spec.sh` — vendor agentnative-spec into `bundle/spec/`
at a pinned `SPEC_REF`. Mirror of the
  agentnative-cli script.
- `bundle/spec/` — vendored agentnative-spec @ v0.2.0: `VERSION`,
`CHANGELOG.md`, `README.md` (resync procedure +
attribution), and seven `principles/p*.md` files with `requirements[]`
frontmatter.
- `bundle/getting-started.md` — three working loops (existing CLI / new
Rust / other language); canonical
`anc check --output json` invocations; "where things live" map covering
spec / references / templates / issue
  routing.
- `.github/ISSUE_TEMPLATE/bundle_proposal.md` — replaces
`principle_proposal.md`; explicitly redirects principle-level
  changes to the spec repo and accepts only bundle-shape proposals.

### Removed

- `bundle/scripts/check-compliance.sh` and 24
`bundle/scripts/checks/check-*.sh` files (plus `_helpers.sh`).
  `anc check --output json` is the canonical replacement.
- `bundle/references/principles-deep-dive.md` (419-line hand-typed
paraphrase of the spec; canonical text now lives
  at `bundle/spec/principles/`).
- `bundle/checklists/new-tool.md` (pre-anc manual checklist; replaced by
`bundle/getting-started.md`).
- `.github/ISSUE_TEMPLATE/principle_proposal.md` (replaced by
`bundle_proposal.md` with corrected routing).
- `.shellcheckrc` (its three disables targeted the deleted bundle
scripts; producer scripts pass shellcheck
  unmodified).

## Type of Change

- [x] `feat`: New feature (non-breaking change which adds functionality)
- [x] `BREAKING CHANGE`: Breaking API change (requires major version
bump)

(Marked both: pivots are additive at the agent-experience level — the
skill now teaches `anc` — but the install
layout is a breaking change for any consumer who was fetching
`bundle/scripts/` or `bundle/checklists/`.)

## Related Issues/Stories

- Story: master plan Unit 1 —
`~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.md`
- Issue: pre-release adversarial audit identified two architecture
mistakes — (a) the bundle was reimplementing what
`anc` already does, (b) the bundle had a hand-typed duplicate of
`agentnative-spec`'s principle text. Both
  resolved here.
- Architecture: aligns this skill with the canonical brettdavies pattern
— `agentnative-cli` vendors the spec via
the same `sync-spec.sh` invariant; this PR makes `agentnative-skill` the
third consumer of that pattern.
- Related PRs: parallel sister PR pending in agentnative-spec to list
`agentnative-skill` as a downstream consumer
  in its top-level `AGENTS.md`.

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [x] Manual testing completed
- [x] All tests passing

**Test Summary:**

- `markdownlint-cli2 '**/*.md'` — 0 errors across 26 markdown files
(vendored `bundle/spec/CHANGELOG.md` is in
  `ignores` per upstream-edited content).
- `shellcheck --severity=style scripts/*.sh` — exit 0 (only producer
scripts remain; bundle has none).
- `actionlint .github/workflows/*.yml` — exit 0.
- `scripts/sync-spec.sh` — verified end-to-end against
`~/dev/agentnative-spec @ v0.2.0`; produces the seven
  expected principle files plus `VERSION` and `CHANGELOG.md`.
- `scripts/generate-changelog.sh --check` — exit 0 (CHANGELOG.md has
versioned section).

## Files Modified

**Modified:**

- `.github/CODEOWNERS`
- `.github/ISSUE_TEMPLATE/bug_report.md`
- `.github/workflows/ci.yml`
- `.markdownlint-cli2.yaml`
- `AGENTS.md`
- `CONTRIBUTING.md`
- `README.md`
- `RELEASES.md`
- `bundle/SKILL.md`

**Created:**

- `bundle/getting-started.md`
- `bundle/spec/{VERSION,CHANGELOG.md,README.md,principles/p1-p7.md}` (10
files)
- `scripts/sync-spec.sh`
- `.github/ISSUE_TEMPLATE/bundle_proposal.md`

**Renamed:**

- `.github/ISSUE_TEMPLATE/principle_proposal.md` →
`.github/ISSUE_TEMPLATE/bundle_proposal.md` (rewritten in place;
retargets to bundle changes only, redirects principle changes upstream)

**Deleted:**

- `bundle/checklists/new-tool.md`
- `bundle/references/principles-deep-dive.md`
- `bundle/scripts/check-compliance.sh`
- `bundle/scripts/checks/_helpers.sh` and 24
`bundle/scripts/checks/check-*.sh` files
- `.shellcheckrc`

## Breaking Changes

- [ ] No breaking changes
- [x] Breaking changes described below:

The skill-install layout changes for any consumer who previously fetched
`bundle/scripts/` or `bundle/checklists/`.
Those paths no longer exist. Replacement workflow:

- For compliance checking, install `anc` (`brew install
brettdavies/tap/agentnative` or
`cargo install agentnative`) and run `anc check --output json`. The full
agent loop is in
  `bundle/getting-started.md`.
- For principle text, read `bundle/spec/principles/p<N>-*.md` (vendored
at the pinned spec ref).
- For onboarding flow, read `bundle/getting-started.md` instead of
`bundle/checklists/new-tool.md`.

Coordinate with the agentnative-site session before tagging v0.2.0 — the
install endpoint at `anc.dev/install`
must adapt to fetch only the surviving bundle paths.

## Deployment Notes

- [ ] No special deployment steps required
- [x] Deployment steps documented below:

This PR lands on `dev` only. The actual v0.2.0 release follows the
`release/*` flow per `RELEASES.md`:

1. Cut `release/v0.2.0` from `origin/main`.
2. Cherry-pick non-docs commits from `dev`: this PR's squash commit +
`893e253` (#1) + `80099fc` (#2) + `bb5dce9`
(#3). Skip the `docs(plan): ...` commits (`632b4d1`, `e8d46e4`,
`774f969`).
3. Bump `VERSION` to `0.2.0`. Run `scripts/generate-changelog.sh` to
populate the `[0.2.0]` section.
4. Open `release/v0.2.0 → main` PR; verify `guard-docs /
check-forbidden-docs` passes.
5. After merge: tag `v0.2.0`, run `gh release create` for both `v0.1.0`
(retroactive) and `v0.2.0`.
6. Updated handoff to agentnative-site session: new SHA + `bundle/`
fetch instruction (only the surviving paths).

## Checklist

- [x] Code follows project conventions and style guidelines
- [x] Commit messages follow [Conventional
Commits](https://www.conventionalcommits.org/)
- [x] Self-review of code completed
- [ ] Tests added/updated and passing
- [x] No new warnings or errors introduced
- [ ] Changes are backward compatible (or breaking changes documented)

…lease pattern, task #15 surfaced)

- Step 9 verification gates: all [ ] checkboxes flipped to [x] with current-state annotations. Visibility gate marked superseded (PUBLIC since 2026-04-28). Force-push gate annotated with the protect-dev bypass-log evidence acquired during the PR #5 redo.
- Step 10 hand-off note: 'still PRIVATE' line marked superseded.
- Additions table: rulesets/README.md row struck through with deletion note (5d93913). RELEASES.md row updated to reflect that PR #3 rewrote it from lightweight to canonical cherry-pick pattern.
- Adopted release pattern: corrected to match current on-disk RELEASES.md (release/v<X.Y.Z> cherry-pick). The earlier 'lightweight no-cherry-pick' claim was accurate at PR #2 time but stale post-PR-#3.
- Outstanding tasks: surfaced bootstrap session task #15 (v0.2.0 release) as the one remaining open item, with concrete cherry-pick scope table (PR-#1 through PR-#5 + 5d93913, with the PR #5 docs/plans hunk to drop).

)

## Summary

PR #3 moved consumer-facing skill content into `bundle/` as an aesthetic
separation between consumer and producer surfaces. That separation
conflicts with the actual install model — site's `skill.json` runs plain
`git clone --depth 1` into `<host>/skills/agent-native-cli/`, which
lands `SKILL.md` at `<skill-root>/bundle/SKILL.md` instead of
`<skill-root>/SKILL.md` where Claude Code, Codex, Cursor, and OpenCode
expect to find it. Without this fix, **no host loads the skill on launch
day.**

Resolution: revert to the gstack-style flat layout. Plain `git clone`
produces a working install; `git pull --ff-only` produces a working
update; producer-ops files (`scripts/`, `docs/`, `.github/`,
`cliff.toml`, `AGENTS.md`, etc.) clone alongside but are inert at
runtime. Same shape gstack ships at `~/.claude/skills/gstack/`.

## Changelog

### Changed

- **BREAKING (install layout):** Skill content moved out of `bundle/` to
the repo root. After install, hosts find `SKILL.md` at the skill root
(where Claude Code expects it), not at `<skill-root>/bundle/SKILL.md`.
Plain `git clone --depth 1` and `git pull --ff-only` are now the
load-bearing install + update commands; no sparse-checkout magic, no
post-install scripts.
- `bin/check-update`: `SKILL_DIR` is now one dir up from the script (was
two), since there's no `bundle/` layer.
- `scripts/sync-spec.sh` writes to `spec/` (was `bundle/spec/`).
- README, AGENTS, CONTRIBUTING reframe the consumer/producer split from
a directory boundary (`bundle/` vs everything else) to an audience
boundary (host reads `SKILL.md` + `bin/` + `spec/` + `references/` +
`templates/` + `VERSION`; ignores everything else).

## Type of Change

- [x] `refactor`: Code refactoring (no functional changes)
- [x] `BREAKING CHANGE`: Breaking API change (requires major version
bump for v1.0+; ships in v0.x minor under SemVer 0.x convention)

## Related Issues/Stories

- Fixes the install-layout incoherence surfaced during U2 smoke-test
planning.
- Folds into v0.2.0 cherry-pick scope. Bootstrap plan task #15
(`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md`) gets a
new candidate row.
- Site team: `skill.json` install command stays as-is — no site-side
change needed.

## Testing

- [x] Unit/integration/e2e/red-team battery (40 tests) re-run against
new layout. **40 pass / 0 fail.**
- [x] `shellcheck bin/check-update`: clean.
- [x] `bash -n bin/check-update`: clean.
- [x] `markdownlint-cli2` clean on all touched files (PostToolUse hook
ran on each edit).
- [x] CI on this branch (markdownlint + shellcheck) is the gating signal
— expect green.

**Test Summary:**

The 40-test battery covers: VERSION read paths (missing,
whitespace-only, surrounding whitespace), disabled sentinel (set +
cleared), HOME unset, snooze parser (level 1/2/3 escalation, expiry,
version-reset, corrupt 1-field, non-numeric level/epoch), cache
freshness (cold start, fast-path UP_TO_DATE, fast-path
UPGRADE_AVAILABLE, stale TTL re-fetch, version drift mid-cache, corrupt
cache), remote validation (valid SemVer, pre-release, build-metadata,
HTML response, empty response, file-URL nonexistent), real-network
GitHub fetch, e2e clone-layout invocation, and red-team injection /
non-ASCII / read-only state / symlink-attack scenarios.

## Files Modified

**Renamed (28 files):**

- `bundle/SKILL.md` → `SKILL.md`
- `bundle/getting-started.md` → `getting-started.md`
- `bundle/bin/check-update` → `bin/check-update`
- `bundle/references/*` → `references/*` (4 files)
- `bundle/spec/*` → `spec/*` (CHANGELOG, README, VERSION, 7 principle
files)
- `bundle/templates/*` → `templates/*` (4 files)

**Modified prose to drop `bundle/` path prefixes:**

- `SKILL.md`, `getting-started.md`, `README.md`, `AGENTS.md`,
`CONTRIBUTING.md`, `RELEASES.md`, `spec/README.md`
- `.github/ISSUE_TEMPLATE/bug_report.md`,
`.github/ISSUE_TEMPLATE/bundle_proposal.md`
- `.markdownlint-cli2.yaml`
- `scripts/sync-spec.sh`

**Modified script:**

- `bin/check-update` — `SKILL_DIR` resolves to `(dirname $0)/..` (one
level), not two. Comment header updated. Env var name
`AGENTNATIVE_SKILL_DIR` unchanged (still the install root override). All
40 battery tests still pass.

## Breaking Changes

- [x] Breaking changes described:

**Path break:** Any v0.1.0 install that pinned to `bundle/*` paths will
break on `git pull`. **Mitigation:** v0.1.0 was never publicly consumed
(private until 2026-04-28; only this session's testing has done git
clones). v0.2.0 ships with the flat layout; consumers see the corrected
layout on first install, no migration needed.

## Deployment Notes

- [x] No special deployment steps required from this repo.
- Cherry-picks into `release/v0.2.0` after merge to `dev`. Adds one row
to the task #15 cherry-pick scope table.

## Additional Context

**Out of scope, intentionally:**

- Sparse-checkout install command (rejected during planning — breaks
`git pull --ff-only` updates).
- Setup script post-install (rejected — same break + adds bootstrap
complexity).
- Hiding producer-ops files into a `_meta/` or `.producer/` dir
(deferred — additive cleanup, not launch-blocking).

**The install model is now coherent end-to-end:**

```bash
# install
git clone --depth 1 https://github.com/brettdavies/agentnative-skill.git ~/.claude/skills/agent-native-cli
# update
cd ~/.claude/skills/agent-native-cli && git pull --ff-only
# uninstall
rm -rf ~/.claude/skills/agent-native-cli
```

Bump VERSION to 0.2.0 and regenerate CHANGELOG via
scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2,
#3, #4, #6, #7, #8, #9, #11 plus the in-cherry-pick spec re-vendor +
RELEASES coordination edits).

Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

)

## Summary

PR #3 moved consumer-facing skill content into `bundle/` as an aesthetic
separation between consumer and producer surfaces. That separation
conflicts with the actual install model — site's `skill.json` runs plain
`git clone --depth 1` into `<host>/skills/agent-native-cli/`, which
lands `SKILL.md` at `<skill-root>/bundle/SKILL.md` instead of
`<skill-root>/SKILL.md` where Claude Code, Codex, Cursor, and OpenCode
expect to find it. Without this fix, **no host loads the skill on launch
day.**

Resolution: revert to the gstack-style flat layout. Plain `git clone`
produces a working install; `git pull --ff-only` produces a working
update; producer-ops files (`scripts/`, `docs/`, `.github/`,
`cliff.toml`, `AGENTS.md`, etc.) clone alongside but are inert at
runtime. Same shape gstack ships at `~/.claude/skills/gstack/`.

## Changelog

### Changed

- **BREAKING (install layout):** Skill content moved out of `bundle/` to
the repo root. After install, hosts find `SKILL.md` at the skill root
(where Claude Code expects it), not at `<skill-root>/bundle/SKILL.md`.
Plain `git clone --depth 1` and `git pull --ff-only` are now the
load-bearing install + update commands; no sparse-checkout magic, no
post-install scripts.
- `bin/check-update`: `SKILL_DIR` is now one dir up from the script (was
two), since there's no `bundle/` layer.
- `scripts/sync-spec.sh` writes to `spec/` (was `bundle/spec/`).
- README, AGENTS, CONTRIBUTING reframe the consumer/producer split from
a directory boundary (`bundle/` vs everything else) to an audience
boundary (host reads `SKILL.md` + `bin/` + `spec/` + `references/` +
`templates/` + `VERSION`; ignores everything else).

## Type of Change

- [x] `refactor`: Code refactoring (no functional changes)
- [x] `BREAKING CHANGE`: Breaking API change (requires major version
bump for v1.0+; ships in v0.x minor under SemVer 0.x convention)

## Related Issues/Stories

- Fixes the install-layout incoherence surfaced during U2 smoke-test
planning.
- Folds into v0.2.0 cherry-pick scope. Bootstrap plan task #15
(`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md`) gets a
new candidate row.
- Site team: `skill.json` install command stays as-is — no site-side
change needed.

## Testing

- [x] Unit/integration/e2e/red-team battery (40 tests) re-run against
new layout. **40 pass / 0 fail.**
- [x] `shellcheck bin/check-update`: clean.
- [x] `bash -n bin/check-update`: clean.
- [x] `markdownlint-cli2` clean on all touched files (PostToolUse hook
ran on each edit).
- [x] CI on this branch (markdownlint + shellcheck) is the gating signal
— expect green.

**Test Summary:**

The 40-test battery covers: VERSION read paths (missing,
whitespace-only, surrounding whitespace), disabled sentinel (set +
cleared), HOME unset, snooze parser (level 1/2/3 escalation, expiry,
version-reset, corrupt 1-field, non-numeric level/epoch), cache
freshness (cold start, fast-path UP_TO_DATE, fast-path
UPGRADE_AVAILABLE, stale TTL re-fetch, version drift mid-cache, corrupt
cache), remote validation (valid SemVer, pre-release, build-metadata,
HTML response, empty response, file-URL nonexistent), real-network
GitHub fetch, e2e clone-layout invocation, and red-team injection /
non-ASCII / read-only state / symlink-attack scenarios.

## Files Modified

**Renamed (28 files):**

- `bundle/SKILL.md` → `SKILL.md`
- `bundle/getting-started.md` → `getting-started.md`
- `bundle/bin/check-update` → `bin/check-update`
- `bundle/references/*` → `references/*` (4 files)
- `bundle/spec/*` → `spec/*` (CHANGELOG, README, VERSION, 7 principle
files)
- `bundle/templates/*` → `templates/*` (4 files)

**Modified prose to drop `bundle/` path prefixes:**

- `SKILL.md`, `getting-started.md`, `README.md`, `AGENTS.md`,
`CONTRIBUTING.md`, `RELEASES.md`, `spec/README.md`
- `.github/ISSUE_TEMPLATE/bug_report.md`,
`.github/ISSUE_TEMPLATE/bundle_proposal.md`
- `.markdownlint-cli2.yaml`
- `scripts/sync-spec.sh`

**Modified script:**

- `bin/check-update` — `SKILL_DIR` resolves to `(dirname $0)/..` (one
level), not two. Comment header updated. Env var name
`AGENTNATIVE_SKILL_DIR` unchanged (still the install root override). All
40 battery tests still pass.

## Breaking Changes

- [x] Breaking changes described:

**Path break:** Any v0.1.0 install that pinned to `bundle/*` paths will
break on `git pull`. **Mitigation:** v0.1.0 was never publicly consumed
(private until 2026-04-28; only this session's testing has done git
clones). v0.2.0 ships with the flat layout; consumers see the corrected
layout on first install, no migration needed.

## Deployment Notes

- [x] No special deployment steps required from this repo.
- Cherry-picks into `release/v0.2.0` after merge to `dev`. Adds one row
to the task #15 cherry-pick scope table.

## Additional Context

**Out of scope, intentionally:**

- Sparse-checkout install command (rejected during planning — breaks
`git pull --ff-only` updates).
- Setup script post-install (rejected — same break + adds bootstrap
complexity).
- Hiding producer-ops files into a `_meta/` or `.producer/` dir
(deferred — additive cleanup, not launch-blocking).

**The install model is now coherent end-to-end:**

```bash
# install
git clone --depth 1 https://github.com/brettdavies/agentnative-skill.git ~/.claude/skills/agent-native-cli
# update
cd ~/.claude/skills/agent-native-cli && git pull --ff-only
# uninstall
rm -rf ~/.claude/skills/agent-native-cli
```

Bump VERSION to 0.2.0 and regenerate CHANGELOG via
scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2,
#3, #4, #6, #7, #8, #9, #10, #11). PR bodies were audited by
parallel subagents against .github/pull_request_template.md before
this regen — empty stubs removed, missing template sections
added, internal-detail bullets moved out of ## Changelog, PR #11's
nested sub-bullets flattened so the generator preserves them.

Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

)

## Summary

PR #3 moved consumer-facing skill content into `bundle/` as an aesthetic
separation between consumer and producer surfaces. That separation
conflicts with the actual install model — site's `skill.json` runs plain
`git clone --depth 1` into `<host>/skills/agent-native-cli/`, which
lands `SKILL.md` at `<skill-root>/bundle/SKILL.md` instead of
`<skill-root>/SKILL.md` where Claude Code, Codex, Cursor, and OpenCode
expect to find it. Without this fix, **no host loads the skill on launch
day.**

Resolution: revert to the gstack-style flat layout. Plain `git clone`
produces a working install; `git pull --ff-only` produces a working
update; producer-ops files (`scripts/`, `docs/`, `.github/`,
`cliff.toml`, `AGENTS.md`, etc.) clone alongside but are inert at
runtime. Same shape gstack ships at `~/.claude/skills/gstack/`.

## Changelog

### Changed

- **BREAKING (install layout):** Skill content moved out of `bundle/` to
the repo root. After install, hosts find `SKILL.md` at the skill root
(where Claude Code expects it), not at `<skill-root>/bundle/SKILL.md`.
Plain `git clone --depth 1` and `git pull --ff-only` are now the
load-bearing install + update commands; no sparse-checkout magic, no
post-install scripts.
- `bin/check-update`: `SKILL_DIR` is now one dir up from the script (was
two), since there's no `bundle/` layer.
- `scripts/sync-spec.sh` writes to `spec/` (was `bundle/spec/`).
- README, AGENTS, CONTRIBUTING reframe the consumer/producer split from
a directory boundary (`bundle/` vs everything else) to an audience
boundary (host reads `SKILL.md` + `bin/` + `spec/` + `references/` +
`templates/` + `VERSION`; ignores everything else).

## Type of Change

- [x] `refactor`: Code refactoring (no functional changes)
- [x] `BREAKING CHANGE`: Breaking API change (requires major version
bump for v1.0+; ships in v0.x minor under SemVer 0.x convention)

## Related Issues/Stories

- Fixes the install-layout incoherence surfaced during U2 smoke-test
planning.
- Folds into v0.2.0 cherry-pick scope. Bootstrap plan task #15
(`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md`) gets a
new candidate row.
- Site team: `skill.json` install command stays as-is — no site-side
change needed.

## Testing

- [x] Unit/integration/e2e/red-team battery (40 tests) re-run against
new layout. **40 pass / 0 fail.**
- [x] `shellcheck bin/check-update`: clean.
- [x] `bash -n bin/check-update`: clean.
- [x] `markdownlint-cli2` clean on all touched files (PostToolUse hook
ran on each edit).
- [x] CI on this branch (markdownlint + shellcheck) is the gating signal
— expect green.

**Test Summary:**

The 40-test battery covers: VERSION read paths (missing,
whitespace-only, surrounding whitespace), disabled sentinel (set +
cleared), HOME unset, snooze parser (level 1/2/3 escalation, expiry,
version-reset, corrupt 1-field, non-numeric level/epoch), cache
freshness (cold start, fast-path UP_TO_DATE, fast-path
UPGRADE_AVAILABLE, stale TTL re-fetch, version drift mid-cache, corrupt
cache), remote validation (valid SemVer, pre-release, build-metadata,
HTML response, empty response, file-URL nonexistent), real-network
GitHub fetch, e2e clone-layout invocation, and red-team injection /
non-ASCII / read-only state / symlink-attack scenarios.

## Files Modified

**Renamed (28 files):**

- `bundle/SKILL.md` → `SKILL.md`
- `bundle/getting-started.md` → `getting-started.md`
- `bundle/bin/check-update` → `bin/check-update`
- `bundle/references/*` → `references/*` (4 files)
- `bundle/spec/*` → `spec/*` (CHANGELOG, README, VERSION, 7 principle
files)
- `bundle/templates/*` → `templates/*` (4 files)

**Modified prose to drop `bundle/` path prefixes:**

- `SKILL.md`, `getting-started.md`, `README.md`, `AGENTS.md`,
`CONTRIBUTING.md`, `RELEASES.md`, `spec/README.md`
- `.github/ISSUE_TEMPLATE/bug_report.md`,
`.github/ISSUE_TEMPLATE/bundle_proposal.md`
- `.markdownlint-cli2.yaml`
- `scripts/sync-spec.sh`

**Modified script:**

- `bin/check-update` — `SKILL_DIR` resolves to `(dirname $0)/..` (one
level), not two. Comment header updated. Env var name
`AGENTNATIVE_SKILL_DIR` unchanged (still the install root override). All
40 battery tests still pass.

## Breaking Changes

- [x] Breaking changes described:

**Path break:** Any v0.1.0 install that pinned to `bundle/*` paths will
break on `git pull`. **Mitigation:** v0.1.0 was never publicly consumed
(private until 2026-04-28; only this session's testing has done git
clones). v0.2.0 ships with the flat layout; consumers see the corrected
layout on first install, no migration needed.

## Deployment Notes

- [x] No special deployment steps required from this repo.
- Cherry-picks into `release/v0.2.0` after merge to `dev`. Adds one row
to the task #15 cherry-pick scope table.

## Additional Context

**Out of scope, intentionally:**

- Sparse-checkout install command (rejected during planning — breaks
`git pull --ff-only` updates).
- Setup script post-install (rejected — same break + adds bootstrap
complexity).
- Hiding producer-ops files into a `_meta/` or `.producer/` dir
(deferred — additive cleanup, not launch-blocking).

**The install model is now coherent end-to-end:**

```bash
# install
git clone --depth 1 https://github.com/brettdavies/agentnative-skill.git ~/.claude/skills/agent-native-cli
# update
cd ~/.claude/skills/agent-native-cli && git pull --ff-only
# uninstall
rm -rf ~/.claude/skills/agent-native-cli
```

Bump VERSION to 0.2.0 and regenerate CHANGELOG via
scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2,
#3, #4, #6, #7, #8, #9, #10, #11, #13). PR bodies were audited by
parallel subagents against .github/pull_request_template.md before
this regen.

PR #13 added CHANGELOG.md to .markdownlint-cli2.yaml ignores so the
generated long-line bullets no longer trip MD013 on the release CI run.

Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

## Summary

First public release of the `agent-native-cli` skill bundle
(`agentnative-skill` repo). Establishes the canonical
brettdavies cherry-pick release pattern (`feature → dev → release/* →
main`), ships the flat install layout consumers
will pull via plain `git clone`, and lands the consumer-side
update-check mechanism that replaces the deprecated
`install.json` SHA-pin advisory.

Cherry-picks 10 dev PRs (#1–#4, #6–#11, #13) onto `origin/main` plus
three direct-to-release-branch fixup commits
(`9f6e276`, `23e1a76` from the bootstrap window) and the curated
`chore(release): v0.2.0` commit. PR #5 (docs-only
public-flip follow-up) stayed on `dev` per the cherry-pick rule. The
original in-cherry-pick spec re-vendor
(`837ab9a` → `1640460`) was converted to a real PR (#10) so the v0.2.0
CHANGELOG carries a curated bullet for the
spec v0.2.0 → v0.3.0 bump.

PR-body template alignment was audited by parallel subagents before this
regeneration — empty stubs removed, missing
template sections added, internal-detail bullets moved out of `##
Changelog`, PR #11's nested sub-bullets flattened.

## Changelog

### Added

- Version-controlled GitHub repository rulesets for `main`, `dev`, and
release tags (`v*`). Apply procedure documented in
`.github/rulesets/README.md`. by @brettdavies in #1
- `AGENTS.md` (root) describing the bundle layout, lint commands, branch
model, and hard rules for agents. by @brettdavies in #2
- `RELEASES.md` (root) documenting a release procedure for this repo
(later rewritten in #3 to the canonical full `release/*` pattern).
- `.github/pull_request_template.md` (canonical PR template).
- `.github/workflows/guard-main-docs.yml` caller for the
`brettdavies/.github` reusable workflow that blocks `docs/plans/`,
`docs/solutions/`, `docs/brainstorms/`, `docs/reviews/` from PRs
targeting `main`.
- `cliff.toml` — git-cliff configuration mirroring sibling repos. by
@brettdavies in #3
- `scripts/generate-changelog.sh` — release-time CHANGELOG generator.
Reads PR-body `## Changelog` sections and prepends a curated, attributed
`[X.Y.Z]` section. Authoritative; never hand-edit `CHANGELOG.md`.
- `CONTRIBUTING.md` — how to propose changes, link to release procedure.
- `.github/ISSUE_TEMPLATE/bug_report.md` + `bundle_proposal.md`
(replaces `principle_proposal.md` with corrected routing).
- Vendored `spec/` tree from `agentnative-spec` — `VERSION`,
`CHANGELOG.md`, `README.md`, and seven `principles/p*.md` files with
machine-readable `requirements[]` frontmatter. The skill points at this
canonical text instead of paraphrasing. by @brettdavies in #4
- `getting-started.md` covering three working agent loops (existing CLI
/ new Rust / other language), canonical `anc check --output json`
invocations, and a "where things live" map.
- `scripts/sync-spec.sh` for re-vendoring `agentnative-spec` on demand.
- `LICENSE-APACHE` — dual-license under MIT or Apache-2.0 (consumer's
choice). by @brettdavies in #6
- `bin/check-update` — gstack-style consumer-side update-check. Compares
the installed `VERSION` against the producer repo's `main`, emits
`UPGRADE_AVAILABLE <local> <remote>`, with cache TTL (60 min UP_TO_DATE
/ 720 min UPGRADE_AVAILABLE) and 3-level snooze (24h / 48h / 7d). State
directory: `$HOME/.cache/agent-native-cli/`. by @brettdavies in #8
- `SKILL.md` `## Update check` section documenting the script's
invocation and the `AskUserQuestion`-driven upgrade flow.

### Changed

- **BREAKING (install layout):** Skill content lives at the repo root
(`SKILL.md`, `bin/`, `spec/`, `references/`, `templates/`, `VERSION`).
Plain `git clone --depth 1` and `git pull --ff-only` are the
load-bearing install + update commands; no sparse-checkout magic, no
post-install scripts. by @brettdavies in #9 (final flat shape;
intermediate `bundle/` indirection from #3 reverted before launch).
- License changed from MIT-only to dual MIT or Apache-2.0 (no MIT
compatibility regression). by @brettdavies in #6
- Documentation now points at `https://anc.dev/skill` instead of
`https://anc.dev/install`. by @brettdavies in #7
- Spec content vendored under `spec/` re-vendored from
`agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status:
draft` → `status: active`; prose tightened across P1–P7 from upstream's
G11 red-team pass. No requirement IDs added/removed/renamed; no level
changes. by @brettdavies in #10
- `scripts/sync-spec.sh` no longer accepts `SPEC_REF`. The script always
vendors the latest `v*` tag, queried from `SPEC_REMOTE_URL` (default
`https://github.com/brettdavies/agentnative.git`) via `git ls-remote
--tags --sort=-version:refname` and shallow-cloned for extraction. On
any remote failure, falls back to the existing `SPEC_ROOT`-based logic
(default `$HOME/dev/agentnative-spec`). New env var `SPEC_REMOTE_URL`
overrides the remote; the temp clone is auto-cleaned on script exit via
trap. by @brettdavies in #11

### Fixed

- Harden `bin/check-update` against malformed local `VERSION` (apply
SemVer regex; malformed → silent exit) and against curl failure being
cached as UP_TO_DATE (skip cache write on network failure so the next
invocation retries). by @brettdavies in #8
- Align table pipes in `SKILL.md` and `getting-started.md` (markdownlint
MD060). by @brettdavies in #9

### Documentation

- `README.md` — License section rewritten to reflect dual licensing and
link both LICENSE files; tree row updated. by @brettdavies in #6
- `CONTRIBUTING.md` — License section rewritten: contributions are
dual-licensed at the consumer's option, no CLA, with an explicit pointer
to the Apache §3 patent grant.
- - `.markdownlint-cli2.yaml` excludes `CHANGELOG.md` from linting
(matches the existing exclusion for `spec/CHANGELOG.md`). Aligns lint
behavior with the `scripts/generate-changelog.sh` regen flow. by
@brettdavies in #13
- All public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`,
`spec/README.md`, `CONTRIBUTING.md`) scrubbed of SHA-pin model
vocabulary: pipeline diagram's "site re-pins to commit SHA" step, the
post-merge "site re-pins via its own PR" step, the `protect-tags.json` /
`install endpoints` claims that tags are pinned to install endpoints,
and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is
recorded" vocabulary across all docs. The new model is plain `git clone`
+ `bin/check-update` for staleness; nothing pins to anything cross-repo.
by @brettdavies in #11

### Removed

- `bundle/scripts/check-compliance.sh` and 24
`bundle/scripts/checks/check-*.sh` files (plus `_helpers.sh`). `anc
check --output json` is the canonical replacement. by @brettdavies in #4
- `bundle/references/principles-deep-dive.md` (419-line hand-typed
paraphrase of the spec; canonical text now lives at `spec/principles/`).
- `.github/ISSUE_TEMPLATE/principle_proposal.md` (replaced by
`bundle_proposal.md` with corrected routing).
- `.shellcheckrc` (its three disables targeted the deleted bundle
scripts; producer scripts pass shellcheck unmodified).

## Type of Change

- [x] `chore`: Maintenance tasks (release engineering)
- [x] `BREAKING CHANGE`: Install layout changes (no v0.1.0 consumers
exist; see Breaking Changes section)

## Related Issues/Stories

- Architecture:
`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` —
bootstrap plan (task #15: launch-eve cherry-pick + admin-bypass decision
recorded `2026-04-28`).
- Architecture:
`docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` —
update-check mechanism plan (drove PR #8 + the SHA-pin removal across PR
#11 / repo docs).
- Cross-repo: `agentnative-cli` — `scripts/sync-spec.sh` is the
documented mirror; lockstep modernization is being driven in a parallel
session.
- Cross-repo: `agentnative-site` — installs this skill via
`https://anc.dev/skill`; the `install.json` SHA-pin advisory is being
removed in that repo (separate PR there) per the update-check plan's
downstream coordination.

## Testing

- [x] Manual testing completed
- [x] All tests passing (CI: markdownlint + shellcheck on every
cherry-picked commit)

**Test Summary:**

- `markdownlint-cli2` clean across the cherry-pick chain (PostToolUse
hook ran on every edit; CI re-verified each PR).
- `shellcheck --severity=style scripts/sync-spec.sh bin/check-update`:
clean.
- `bash -n scripts/sync-spec.sh bin/check-update`: clean.
- `bin/check-update` 40-test battery (PR #8): 40 pass / 0 fail (unit +
integration + e2e + red-team).
- `scripts/sync-spec.sh` remote-success path verified live: queried
`https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`,
shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.
Remote-fail-local-success path verified by setting bogus
`SPEC_REMOTE_URL` (warning + fallback to `$HOME/dev/agentnative-spec`).
Both-fail path verified with bogus URL + bogus `SPEC_ROOT` (hard error
with both printed).
- Vocabulary check: `rg` for `SHA-pin` / `commit SHA` / `source.commit`
/ `install.json` / `re-pin` / `SPEC_REF` / `pin` / `pinned` / `pinning`
across shipping content (excluding `docs/plans/`, license boilerplate,
changelogs, vendored `spec/principles/`): **zero** matches.
- PR-body template alignment: parallel audit subagents reported
`verified=true` for PRs #1–#11.

## Files Modified

**Cherry-picked from dev (squash commits):**

- `8be19e6` — feat(bundle): consumer-side update-check mechanism (U1+U2)
[#8]
- `34b1da3` — refactor!: flatten bundle/* to repo root for plain
git-clone install [#9]
- `4461806` — chore(spec): re-vendor spec/ to v0.3.0 + RELEASES
spec-revendor section [#10]
- `fb50d18` — chore(sync-spec): drop SHA-pin claims, modernize to
remote-first vendoring [#11]
- `e67523e` — chore(lint): exclude CHANGELOG.md from markdownlint [#13]
(added during release prep to unblock MD013 on the rich generated
CHANGELOG)

**Direct-to-release-branch fixup commits (bootstrap window):**

- `9f6e276` — chore(rulesets): drop `.github/rulesets/README.md`
- `23e1a76` — docs(bundle): trim trailing platform comment on `cargo
install` line

**Curated release commit:**

- `d66d5bd` — chore(release): v0.2.0 (VERSION bump + regenerated
CHANGELOG.md)

**Plus PRs #1–#7 cherry-picked earlier in the bootstrap window:**
rulesets (#1), AGENTS/PR-template/RELEASES scaffold (#2), bundle
restructure + cliff.toml (#3), spec vendoring + skill pivot (#4), dual
licensing (#6), `/skill` endpoint rename (#7).

## Breaking Changes

- [x] Breaking changes described below

**Install layout (PR #4 + PR #9):** the skill bundle's directory shape
went from a paraphrased pre-anc layout (v0.1.0) → `bundle/` subdirectory
(PR #3) → flat root (PR #9). The flat root is the load-bearing final
shape: `git clone --depth 1` lands `SKILL.md` at the install root where
Claude Code, Codex, Cursor, and OpenCode auto-discover it.

**No real-world migration impact:** v0.1.0 has zero installed consumers
(the install endpoint at `https://anc.dev/skill` is gated by this very
release). The breaking-change classification is for SemVer hygiene, not
user-impacting.

**Bundle surface contract (PR #4):** the skill no longer ships
shell-script compliance checks (`bundle/scripts/check-compliance.sh` +
24 `check-*.sh` files). `anc check --output json` is the canonical
replacement; downstream tools that scraped the old shell scripts must
migrate to `anc`.

## Deployment Notes

- [x] Deployment steps documented below

**Pre-merge admin-bypass (one-time):** the `protect-main` ruleset
requires `markdownlint`, `shellcheck`, and `guard-docs /
check-forbidden-docs` as required status checks. The third comes from
`guard-main-docs.yml`, which only exists on `dev` (it's part of this
very release). For the FIRST release PR, GitHub evaluates `pull_request`
workflows from `main` (the base), so the guard-docs check cannot run.
Resolution: admin-bypass this single PR via the existing `bypass_actors`
on `protect-main` (`actor_type: RepositoryRole, actor_id: 5,
bypass_mode: always`). One-off; subsequent releases run cleanly. See
bootstrap plan §15 (decision recorded `2026-04-28`).

**Post-merge sequence (per RELEASES.md):**

1. Tag the squash commit on `main`:

   ```bash
   git checkout main && git pull
   git tag -a v0.2.0 -m "v0.2.0"
   git push origin v0.2.0
   ```

2. Create the GitHub Release with the v0.2.0 CHANGELOG section as notes:

   ```bash
   gh release create v0.2.0 --title "v0.2.0" \
--notes "$(awk '/^## \[0\.2\.0\]/{flag=1; next} /^## \[/{flag=0} flag'
CHANGELOG.md)"
   ```

3. Consumers detect the new release on their next `bin/check-update`
run; no site-side coordination step (the SHA-pin model is gone, per
#11).

## Checklist

- [x] Code follows project conventions and style guidelines
- [x] Commit messages follow [Conventional
Commits](https://www.conventionalcommits.org/)
- [x] Self-review of code completed
- [x] Tests added/updated and passing (CI green on every cherry-picked
commit)
- [x] No new warnings or errors introduced
- [x] Changes are backward compatible (or breaking changes documented in
Breaking Changes section)

## Additional Context

- Full v0.2.0 entry in [`CHANGELOG.md`](./CHANGELOG.md) (this section is
a copy; CHANGELOG.md is canonical).
- The PR-body audit run produced template-aligned bodies for all 11
merged PRs; CHANGELOG.md was regenerated from the audited bodies before
this PR opened.